<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libcoap: coap_tls_library(3)</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libcoap<span id="projectnumber">&#160;4.2.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('man_coap_tls_library.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">coap_tls_library(3)</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>coap_tls_library</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /></head><body><div xml:lang="en" class="refentry" lang="en"><a id="id1337"></a><div class="titlepage"></div><div class="refnamediv"><h2>NAME</h2><p>coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported, coap_get_tls_library_version, coap_string_tls_version, coap_show_tls_version — Work with CoAP contexts</p></div><div class="refsynopsisdiv"><a id="_synopsis"></a><h2>SYNOPSIS</h2><p><span class="strong"><strong>#include &lt;coap2/coap.h&gt;</strong></span></p><p><span class="strong"><strong>int coap_dtls_is_supported(void);</strong></span></p><p><span class="strong"><strong>int coap_tls_is_supported(void);</strong></span></p><p><span class="strong"><strong>coap_tls_version_t *coap_get_tls_library_version(void);</strong></span></p><p>*char *coap_string_tls_version(char *<span class="emphasis"><em>buffer</em></span>, size_t <span class="emphasis"><em>bufsize</em></span>);</p><p><span class="strong"><strong>void coap_show_tls_version(coap_log_t <span class="emphasis"><em>level</em></span>);</strong></span></p><p>Link with <span class="strong"><strong>-lcoap-2</strong></span>, <span class="strong"><strong>-lcoap-2-gnutls</strong></span>,
<span class="strong"><strong>-lcoap-2-openssl</strong></span> or
<span class="strong"><strong>-lcoap-2-tinydtls</strong></span> depending on your (D)TLS library
type.</p></div><div class="refsect1"><a id="_description"></a><h2>DESCRIPTION</h2><p>When the libcoap library was built, it will have been compiled using a
specific TLS implementation type (e.g. OpenSSL, GnuTLS, TinyDTLS or noTLS).
When the libcoap library is linked into an application, it is possible that
the application needs to dynamically determine whether DTLS or TLS is
supported, what type of TLS implementation libcoap was compiled with, as well
as detect what is the version of the currently loaded TLS library is.</p><p><span class="strong"><strong>NOTE:</strong></span> If OpenSSL is being used, then the minimum OpenSSL library version is
1.1.0.</p><p><span class="strong"><strong>NOTE:</strong></span> If GnuTLS is being used, then the minimum GnuTLS library version is
3.3.0.</p><p><span class="strong"><strong>NOTE:</strong></span> If GnuTLS is going to interoperate with TinyDTLS, then a minimum
revision of GnuTLS 3.5.5 which supports CCM algorithms is required
by TinyDTLS as TinyDTLS currently only supports CCM.</p><p>Network traffic can be encrypted or un-encrypted with libcoap - how to set
this up is described in <a href="man_coap_context.html" target="_self"><span class="strong"><strong>coap_context</strong></span>(3)</a>.</p><p>Due to the nature of TLS, there can be Callbacks that are invoked as the TLS
session negotiates encryption algorithms, encryption keys etc.
Where possible, by default, the CoAP layer handles all this automatically.
However, there is the flexibility of the Callbacks for imposing additional
security checks etc. when PKI is being used.  These callbacks need to need to
match the TLS implementation type.</p><p>The <span class="strong"><strong>coap_dtls_is_supported</strong></span>() function returns 1 if support for DTLS is
enabled, otherwise 0;</p><p>The <span class="strong"><strong>coap_tls_is_supported</strong></span>() function returns 1 if support for TLS is
enabled, otherwise 0;</p><p>The <span class="strong"><strong>coap_get_tls_library_version</strong></span>() function returns the TLS implementation
type and library version in a coap_tls_version_t* structure.</p><p>The <span class="strong"><strong>coap_string_tls_version</strong></span>() function is used to update the provided buffer
with information about the current (D)TLS library that libcoap was built
against, as well as the current linked version of the (D)TLS library.
<span class="emphasis"><em>buffer</em></span> defines the buffer to provide the information and <span class="emphasis"><em>bufsize</em></span> is the
size of <span class="emphasis"><em>buffer</em></span>.</p><p>The <span class="strong"><strong>coap_show_tls_version</strong></span>() function is used log information about the
current (D)TLS library that libcoap was built against, as well as the current
linked version of the (D)TLS library. <span class="emphasis"><em>level</em></span> defines the minimum logging level
for this information to be output using coap_log().</p><pre class="programlisting">#define COAP_TLS_LIBRARY_NOTLS    0
#define COAP_TLS_LIBRARY_TINYDTLS 1
#define COAP_TLS_LIBRARY_OPENSSL  2
#define COAP_TLS_LIBRARY_GNUTLS   3

typedef struct coap_tls_version_t {
  uint64_t version; /* (D)TLS runtime Library Version */
  int type; /* Library type. One of COAP_TLS_LIBRARY_* */
  uint64_t built_version; /* (D)TLS Built against Library Version */
}</pre></div><div class="refsect1"><a id="_return_values"></a><h2>RETURN VALUES</h2><p><span class="strong"><strong>coap_dtls_is_supported</strong></span>() and <span class="strong"><strong>coap_tls_is_supported</strong></span>() functions
return 0 if there is no support, 1 if support is available.</p><p><span class="strong"><strong>coap_get_tls_library_version</strong></span>() function returns the TLS implementation type
and library version in a coap_tls_version_t* structure.</p><p><span class="strong"><strong>coap_string_tls_version</strong></span>() function returns a pointer to the provided buffer.</p></div><div class="refsect1"><a id="_see_also"></a><h2>SEE ALSO</h2><p><a href="man_coap_context.html" target="_self"><span class="strong"><strong>coap_context</strong></span>(3)</a> and <a href="man_coap_logging.html" target="_self"><span class="strong"><strong>coap_logging</strong></span>(3)</a>.</p></div><div class="refsect1"><a id="_further_information"></a><h2>FURTHER INFORMATION</h2><p>See "RFC7252: The Constrained Application Protocol (CoAP)" for further
information.</p></div><div class="refsect1"><a id="_bugs"></a><h2>BUGS</h2><p>Please report bugs on the mailing list for libcoap:
<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a></p></div><div class="refsect1"><a id="_authors"></a><h2>AUTHORS</h2><p>The libcoap project &lt;<a class="ulink" href="mailto:libcoap-developers@lists.sourceforge.net" target="_top">libcoap-developers@lists.sourceforge.net</a>&gt;</p></div></div></body></html> coap_tls_library(3)</p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Fri Dec 27 2024 09:57:44 for libcoap by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8 </li>
  </ul>
</div>
</body>
</html>
